IRIX Base Documentation 2002 November

home *** CD-ROM | disk | FTP | other *** search

/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / ckpt_create.z / ckpt_create

Wrap

Text File | 2002-10-03 | 18.7 KB | 463 lines

cccckkkkpppptttt____ccccrrrreeeeaaaatttteeee((((3333)))) cccckkkkpppptttt____ccccrrrreeeeaaaatttteeee((((3333)))) NNNNAAAAMMMMEEEE ckpt_setup, ckpt_create, ckpt_restart, ckpt_stat, ckpt_remove - checkpoint and restart (CPR) library interfaces SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS #include <ckpt.h> int ckpt_setup(struct ckpt_args *_a_r_g_s[], size_t _n_a_r_g_s); int ckpt_create(const char *_p_a_t_h, ckpt_id_t _i_d, u_long _t_y_p_e, struct ckpt_args *_a_r_g_s[], size_t _n_a_r_g_s); ckpt_id_t ckpt_restart(const char *_p_a_t_h, struct ckpt_args *_a_r_g_s[], size_t _n_a_r_g_s); int ckpt_stat(const char *_p_a_t_h, struct ckpt_stat **_s_p); int ckpt_remove(const char *_p_a_t_h); DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN The functions provided here are used to issue checkpoint and restart (CPR) requests to a process or group of processes. The _c_k_p_t__s_e_t_u_p, _c_k_p_t__c_r_e_a_t_e, _c_k_p_t__r_e_s_t_a_r_t, and _c_k_p_t__r_e_m_o_v_e routines are implemented according to the IEEE standard POSIX 1003.1m Draft 1, with minor modifications (described below). The _c_k_p_t__s_t_a_t function is an IRIX extension. Silicon Graphics intends to follow the future development of POSIX 1003.1m draft standards and endeavor to be compliant. cccckkkkpppptttt____sssseeeettttuuuupppp This routine currently does not perform any operation on IRIX systems. The interface is reserved for future addition of features. The POSIX _c_k_p_t__a_r_g_s structure defined in <ckpt.h> includes the following members: unsigned long ckpt_type; /* data type */ void *ckpt_data; /* data */ None of the POSIX _c_k_p_t__t_y_p_e definitions (CKPT_ID, CKPT_LOCK, CKPT_SIGNAL, CKPT_POSTRESTART, CKPT_PRERESTART, and CKPT_POSTCREATE) is implemented in IRIX because CPR handles these functions directly and transparently. cccckkkkpppptttt____ccccrrrreeeeaaaatttteeee This routine performs a checkpoint operation against a process or group of processes. It creates a set of checkpoint statefiles in the directory _p_a_t_h, based on the user-specified checkpoint ID _i_d, which has a _t_y_p_e as defined in <ckpt.h>: P_PID for Unix process ID P_PGID for Unix process group ID P_SID for Unix process session ID; see _t_e_r_m_i_o(7) P_ASH for IRIX Array Session ID; see _a_r_r_a_y__s_e_r_v_i_c_e_s(5) P_HID for process hierarchy (tree) rooted at that PID P_SGP for IRIX sproc shared group; see _s_p_r_o_c(2) PPPPaaaaggggeeee 1111 cccckkkkpppptttt____ccccrrrreeeeaaaatttteeee((((3333)))) cccckkkkpppptttt____ccccrrrreeeeaaaatttteeee((((3333)))) P_JID for IRIX job ID Note that _c_k_p_t__i_d__t is defined as an _i_n_t_6_4__t type in <ckpt.h>. The original POSIX standard requires _i_d to be a _p_i_d__t which is not long enough to support the SGI 64-bit Array ID (ASH) number or the SGI 64-bit Job ID (JID) number. However, any application binary using regular POSIX _c_k_p_t__c_r_e_a_t_e should work fine since type casting from 32-bit _p_i_d__t to 64- bit _c_k_p_t__i_d__t is transparent. The *_a_r_g_s[] and _n_a_r_g_s arguments from the POSIX draft standard, similar to the definitions in _c_k_p_t__s_e_t_u_p, are ignored in IRIX. See _c_p_r(1) for more information about the CPR attribute file $_H_O_M_E/._c_p_r, checkpointable objects and limitations, the SIGCKPT and SIGRESTART signals, event handling using _a_t_c_h_e_c_k_p_o_i_n_t(3C) and _a_t_r_e_s_t_a_r_t(3C), CPR security, and other issues. In addition to the CPR attribute file, a global variable _c_p_r__f_l_a_g_s defined in <ckpt.h> may specify checkpoint-related options. The options available are: CKPT_OPENFILE_DISTRIBUTE This flag alters the default location, which is the centralized directory given by _p_a_t_h, for saving open files. Instead, open files are saved in the same directory where the original open files resided, with a new and unique name identifying them. For example, if a process has the /_e_t_c/_p_a_s_s_w_d file open when a checkpoint is issued, with the CKPT_OPENFILE_DISTRIBUTE bit set, the /_e_t_c/_p_a_s_s_w_d file is saved distributively in /_e_t_c/_p_a_s_s_w_d._c_k_p_t._p_i_d_X_X_X. Distribute mode is useful when disk space is a concern. However, the centralized mode (the default) is far more secure and self- contained. Users should be cautious when this bit is set. CKPT_CHECKPOINT_CONT This flag makes checkpoint target processes continue running after this checkpoint is finished. It overrides the default WILL policy, and the WILL policy specified in a user's CPR attribute file. CKPT_CHECKPOINT_KILL This flag kills checkpoint target processes after this checkpoint is finished. This is the default WILL policy, but overrides a CONT setting in the user's CPR attribute file. CKPT_CHECKPOINT_UPGRADE Use this flag only when issuing a checkpoint immediately before an operating system upgrade. This forces a save of all executable files and DSO libraries used by the current processes, so that target processes can be restarted in an upgraded environment. This flag must be used again if restarted processes must be recursively checkpointed in the new environment. PPPPaaaaggggeeee 2222 cccckkkkpppptttt____ccccrrrreeeeaaaatttteeee((((3333)))) cccckkkkpppptttt____ccccrrrreeeeaaaatttteeee((((3333)))) CKPT_ATTRFILE_IN_CWD Use this flag if you would like to checkpoint using the CPR attribute file residing in your current working directory (versus $HOME/.cpr). cccckkkkpppptttt____rrrreeeessssttttaaaarrrrtttt This routine restarts a set of processes from the statefile created at checkpoint time and identified by _p_a_t_h. If a restart involves more than one process, the restart on all processes has to succeed before any process is enabled to run. If one restart in a group fails, all fail. In addition to the CPR attribute file, a global variable _c_p_r__f_l_a_g_s defined in <ckpt.h> may specify restart-related options. The options available are: CKPT_RESTART_INTERACTIVE This flag makes a process or group of processes interactive (that is, subject to UNIX job-control), if the original processes were interactive. The calling process or the calling process' group leader becomes the group leader of restarted processes, but the original process group ID cannot be restored. Without this flag, the default is to restart target processes as an independent process group with the original group ID restored. CKPT_ATTRFILE_IN_CWD Use this flag if you would like to restart using the CPR attribute file residing in your current working directory (versus $HOME/.cpr). CKPT_RESTART_MIGRATE This flag migrates process memory so it is restored to the location in the system topology where the restart is executing (within a specific cpuset, within the global cpuset, etc.). Without this option, the default restart behavior on NUMA systems is to restore process memory back to where it was at the time of the checkpoint. This option has no effect on non-NUMA systems. See the _m_i_g_r_a_t_i_o_n(3) man page for scenarios which may prevent pages from migrating properly. cccckkkkpppptttt____rrrreeeemmmmoooovvvveeee This routine deletes a statefile identified by _p_a_t_h. The _c_k_p_t__r_e_m_o_v_e routine removes all statefiles, including all the saved open files, mapped files, pipe data, and so forth. Only the superuser and the checkpoint owner can remove checkpoint files. cccckkkkpppptttt____ssssttttaaaatttt This routine is issued to existing statefiles in _p_a_t_h to get basic information about the checkpointed processes saved there. The information is returned through a single-link list of _c_k_p_t__s_t_a_t__t structures pointed by *_s_p, defined in <ckpt.h>. Each structure represents one process with the following members: PPPPaaaaggggeeee 3333 cccckkkkpppptttt____ccccrrrreeeeaaaatttteeee((((3333)))) cccckkkkpppptttt____ccccrrrreeeeaaaatttteeee((((3333)))) struct ckpt_stat *cs_next; /* next process */ long cs_revision; /* CPR revision # */ pid_t cs_pid; /* proc pid */ pid_t cs_ppid; /* proc parent pid */ pid_t cs_pgrp; /* proc group leader */ pid_t cs_sid; /* session id */ struct stat cs_stat; /* see stat(2) */ char cs_nfiles; /* # of open files */ char cs_comm[PSCOMSIZ]; /* process name */ char cs_psargs[PSARGSZ]; /* and arguments */ char cs_cdir[MAXPATHLEN]; /* current directory */ int cs_board; /* board (sys/invent.h) */ int cs_cpu; /* cpu (sys/invent.h) */ int cs_abi; /* abi (sys/kabi.h) */ Applications can traverse through the next pointer _c_s__n_e_x_t to reach all processes associated with the statefile. It is important to note that although applications are not required to allocate the memory buffers needed for the _s_p linked list, it is an application's responsibility to release these memory buffers after examining the data. Applications should follow the _c_s__n_e_x_t link to free all of the _c_k_p_t__s_t_a_t__t buffers. The following example shows how to use this function: ckpt_stat_t *sp, *sp_next; if (ckpt_stat(path, &sp)) < 0) return (-1); while (sp) { /* examine the data sp */ ... sp_next = sp->cs_next; free(sp); sp = sp_next; } NNNNOOOOTTTTEEEESSSS All the CPR interfaces are found in the _l_i_b_c_p_r._s_o DSO, and are loaded at runtime if the ----llllccccpppprrrr option is passed to _c_c(1) or _l_d(1). The contents of ckpt_stat_t are likely to change between releases. The ckpt_stat() interface is not supported for 32 bit abis running on 64 bit kernels. SSSSEEEEEEEE AAAALLLLSSSSOOOO _c_p_r(1), _c_v_i_e_w(1), _a_t_c_h_e_c_k_p_o_i_n_t(3C), _a_t_r_e_s_t_a_r_t(3C) IEEE standard POSIX 1003.1m Draft 1, October 1995. This draft standard is still being discussed and modified. No assurances can be given as to when P1003.1m will be approved or what it will contain. PPPPaaaaggggeeee 4444 cccckkkkpppptttt____ccccrrrreeeeaaaatttteeee((((3333)))) cccckkkkpppptttt____ccccrrrreeeeaaaatttteeee((((3333)))) DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS _c_k_p_t__s_e_t_u_p is a no-op interface and currently always returns 0. _c_k_p_t__c_r_e_a_t_e returns 0 upon success. Upon failure it returns -1 and sets _e_r_r_n_o to indicate one of the following: [ECKPT] An unrecoverable resource, such as a socket connection, is associated with the target process. [EEXIST] The file named by _p_a_t_h already exists. [ENOMEM] Checkpointing requires more memory than allowed by the hardware or available swap space. [ENOSPC] Space remaining on the device is insufficient for the checkpoint file. [EACCES] Search permission is denied on a component of the path prefix or write permission is denied on the parent directory of the checkpoint file to be created. [EPERM] The calling process does not have appropriate privileges to checkpoint one or more of the target processes. [EBUSY] A resource associated with the target process is in use by the system. [ELOOP] Too many symbolic links were encountered during resolution of the _p_a_t_h argument; a loop probably exists. [ENOENT] The _p_a_t_h argument names a nonexistent directory or points to an empty string. [ENOTDIR] A component of the path prefix is not a directory. [EROFS] The checkpoint file being created would reside on a read-only file system. [EINVAL] An invalid argument was passed to the function call. [ESRCH] The process or process group specified by _i_d cannot be found. PPPPaaaaggggeeee 5555 cccckkkkpppptttt____ccccrrrreeeeaaaatttteeee((((3333)))) cccckkkkpppptttt____ccccrrrreeeeaaaatttteeee((((3333)))) _c_k_p_t__r_e_s_t_a_r_t returns the ID (_c_k_p_t__i_d__t) of the restarted process, process group leader, session leader, tree root of processes in an array, tree root of a process hierarchy, _s_p_r_o_c group leader, or job. Note that the 64-bit return value _c_k_p_t__i_d__t is different from the 32-bit value POSIX specifies; however, the difference doesn't affect API compatibility. On failure, _c_k_p_t__r_e_s_t_a_r_t returns -1 and sets _e_r_r_n_o to indicate one of the following: [ECKPT] Restart operation can not be completed or an unrecoverable resource is associated with the target process. [EBUSY] The system resource required to restart the processes requested is already taken at this moment. For example, a process ID is currently being used by another process and if the action ORIGINAL is set for the FORK function in the $_H_O_M_E/._c_p_r attribute file. [EAGAIN] A system-imposed limit on the total number of processes belonging to a single user (CHILD_MAX) would be exceeded by restarting the target process set. [ENOMEM] Restarting the target process set requires more memory than allowed by the hardware or available swap space. [EACCES] Search permission is denied on a component of the path prefix. [EPERM] The real user ID of the calling process does not match the real user ID of one or more processes defined by the checkpoint file, or the calling process does not have appropriate privileges to restart one or more of the target processes. [ELOOP] Too many symbolic links were encountered during resolution of the _p_a_t_h argument; a loop probably exists. [ENOENT] The _p_a_t_h argument names a nonexistent directory or points to an empty string. [ENOTDIR] A component of the path prefix is not a directory. [EROFS] Restarted files would be created in a read-only file system. PPPPaaaaggggeeee 6666 cccckkkkpppptttt____ccccrrrreeeeaaaatttteeee((((3333)))) cccckkkkpppptttt____ccccrrrreeeeaaaatttteeee((((3333)))) [EINVAL] An invalid argument was passed to the function call. _c_k_p_t__r_e_m_o_v_e and _c_k_p_t__s_t_a_t return 0 on success. On failure, they return -1 and set _e_r_r_n_o to indicate one of the following: [EACCES] Search permission is denied on a component of the path prefix, or write permission is denied on the parent directory of the checkpoint file to be removed. [EPERM] The calling process does not have appropriate privileges to remove or stat the target statefiles. [ELOOP] Too many symbolic links were encountered during resolution of the _p_a_t_h argument; a loop probably exists. [ENOENT] The _p_a_t_h argument names a nonexistent directory or points to an empty string. [ENOTDIR] A component of the path prefix is not a directory. [EROFS] The checkpoint file to be removed resides on a read-only file system. [EINVAL] The file to be removed is not a checkpoint file. PPPPaaaaggggeeee 7777